JavaScript Debugger Modules > What is a JavaScript Debugger Module? > How the JavaScript Debugger Module works

 

How the JavaScript Debugger Module works

Dreamweaver comes with two debugger modules, one for each supported browser: Netscape and Internet Explorer. To provide support for a different browser, you would create a new debugger module, and then use dom.instrumentDocument and dreamweaver.startDebugger to debug the document in the other browser.

When you call dom.instrumentDocument, the specified debugger module receives callbacks as Dreamweaver parses the JavaScript in the document. So, for instance, you could create a debugger module that inserts comments or records information about the JavaScript code, instead of inserting debugging enhancements.

When dom.instrumentDocument is called with a specific debugger module, the following steps occur:

1 Dreamweaver calls getIncludeFiles() in the debugger module. This function returns the list of files that will be referenced from HTML instrumentation code returned from getHeadInstrument() and getBodyInstrument() (which are called later). The include files can be any type of file, such as an external JavaScript file or JavaApplet or ActiveX control. All of the files must be in the Configuration/Debugger subfolder with the Debugger Module. Dreamweaver will copy the include files to the directory that contains the file being debugged, and then later will delete the include files from that directory when Dreamweaver exits.
2 Next, the HTML document is scanned for script tags and event handlers. The code inside the script tag, in an external JavaScript file, or in an event handler is known as a block.
Note: An external JavaScript file is a file that is specified as the "src" attribute of a SCRIPT tag.
3 Dreamweaver parses script tags in the HEAD section first.
4 When Dreamweaver finds a script tag or event handler, it calls the debugger module's startBlock() function and passes in the name of the file and the line and character offsets from the beginning of the file.
5 Then Dreamweaver begins parsing the JavaScript code in the block.
6 When Dreamweaver finds a JavaScript statement, such as a variable declaration, it calls getStepInstrument() passing the line and character offsets and other information. The debugger module returns a string of JavaScript code that is inserted before the statement. You must take care to return valid JavaScript code. For each call to getStepInstrument(), Dreamweaver records the line number as a valid breakpoint line regardless of what instrumentation is returned. So, when the debugger is started with dw.startDebugger(), the breakpoints the user has already set will be moved to one of these valid lines.
7 When Dreamweaver finds a function declaration, it calls the getFunctionStartInstrument() to receive the instrumentation to be inserted at the beginning of the function.
Note: This is not considered a valid breakpoint line.
8 Dreamweaver continues parsing the function and calling getStepInstrument() for each statement in the function.
9 When Dreamweaver comes to a return statement, or the end of the function, it calls getFunctionEndInstument() to receive the instrumentation to be inserted before the function returns.
Note: This is not considered a valid breakpoint line.
10 If Dreamweaver encounters a syntax error or warning in the JavaScript block, it calls reportError() or reportWarning(), respectively. After an error is encountered, Dreamweaver stops parsing the block. Other blocks will still be parsed.
11 After Dreamweaver has parsed all the script blocks in the HEAD section, it calls getHeadInstrument() to get the HTML instrumentation to insert in the HEAD section.
Note: This function should return HTML, not JavaScript. If the debugger module needs to insert JavaScript code in the HEAD, it must enclose it in a SCRIPT tag.
12 Next Dreamweaver begins processing the JavaScript blocks (SCRIPT tags and event handlers) in the BODY section of the document.
13 After the last block in the BODY section is instrumented, Dreamweaver calls getBodyInstrument() to get the HTML instrumentation to insert in the BODY section.
Note: This function should return HTML, not JavaScript.
14 After Dreamweaver calls getBodyInstrument(), there is one final call to startBlock() and getStepInstrument() for an auto-breakpoint. The instrumentation does not correspond to any user-defined SCRIPT tag, but rather is inserted in a new SCRIPT tag after the BODY instrumentation. Unlike other calls to getStepInstrument(), this line is not considered a valid line on which the user can set a breakpoint, but rather it is treated as a special kind of breakpoint at which the debugger always stops.
15 Finally, Dreamweaver calls getOnUnloadInstrument() to get JavaScript instrumentation to be inserted in the onUnload handler of the BODY tag. If the document already has an onUnload handler, this instrumentation is inserted after the user-defined onUnload code.